<html>
<head>
<style type='text/css'>
body {
   background-color: white;
   margin: 1em 2em 1em 2em;
   font-family: Sans-Serif;
   color: #002;
   line-height: 140%;
   font-size: 12px;
}

h1 {
    font-size: 140%;
}

h2 {
    font-size: 130%;
}

h3 {
    font-size: 120%;
}

h4 {
    font-size: 100%;
    font-style: normal;
    font-weight: bold;
}

h5 {
    font-size: 100%;
    font-style: italic;
    font-weight: normal;
}

pre {
   background-color: #eee;
   padding: 0.5em 0.5em 0.5em 2em;
}

@media print {
   pre {word-wrap:break-word; width:100%;}
} 

ul li,
ol li {
   padding-left: 0.3em;
   /*text-indent: -2em;*/
   margin-bottom: 0.5em;
}

em {
   font-style: normal;
   font-weight: bold;
   text-decoration: underline;
   color: #c40;
}

code {
   font-family: Monospace;
   font-size: 100%;
   color: #c40;
}

a, a * {
   text-decoration: underline;
   color: blue;
   /* border: 0.5px solid #aaa;
   white-space: nowrap;
   padding-right: 0.1em;
   padding-left: 0.1em;
   padding-bottom: -5px; */
}

a code {
   color: blue;
}

img {
   position: relative;
   bottom: -4px;
}

div.headline {
   font-weight: bold;
   font-size: 110%;
}

div.copyright {
   margin-top: 1em;
   border-top: 1px solid black;
   padding-top: 0.5em;
}

div.iris_headline {
   border-bottom: 1px solid black;
   padding-bottom: 0.3em;
}

.LaTeX {
   font-family: Monospace;
   font-size: 100%;
   border: 1px solid #060;
   color: #060;
}

code.LaTeX {
   background-color: white;
   padding: 0.5em 0.5em 0.5em 2em;
}
</style>
</head>

<body>
<div class="iris_headline">IRIS Toolbox Reference Manual</div>




<h2 id="poster/arwm">arwm</h2>
<div class="headline">Adaptive random-walk Metropolis posterior simulator</div>

<h4 id="syntax">Syntax</h4>
<pre><code>[Theta,LogPost,ArVec,PosUpd] = arwm(Pos,NDraw,...)
[Theta,LogPost,ArVec,PosUpd,SgmVec,FinalCov] = arwm(Pos,NDraw,...)</code></pre>
<h4 id="input-arguments">Input arguments</h4>
<ul>
<li><p><code>Pos</code> [ poster ] - Initialised posterior simulator object.</p></li>
<li><p><code>NDraw</code> [ numeric ] - Length of the chain not including burn-in.</p></li>
</ul>
<h4 id="output-arguments">Output arguments</h4>
<ul>
<li><p><code>Theta</code> [ numeric ] - MCMC chain with individual parameters in rows.</p></li>
<li><p><code>LogPost</code> [ numeric ] - Vector of log posterior density (up to a constant) in each draw.</p></li>
<li><p><code>ArVec</code> [ numeric ] - Vector of cumulative acceptance ratios.</p></li>
<li><p><code>PosUpd</code> [ poster ] - Posterior simulator object with its properties updated so to capture the final state of the simulation.</p></li>
<li><p><code>SgmVec</code> [ numeric ] - Vector of proposal scale factors in each draw.</p></li>
<li><p><code>FinalCov</code> [ numeric ] - Final proposal covariance matrix; the final covariance matrix of the random walk step is Scale(end)^2*FinalCov.</p></li>
</ul>
<h4 id="options">Options</h4>
<ul>
<li><p><code>'adaptProposalCov='</code> [ numeric | <em><code>0.5</code></em> ] - Speed of adaptation of the Cholesky factor of the proposal covariance matrix towards the target acceptanace ratio, <code>targetAR</code>; zero means no adaptation.</p></li>
<li><p><code>'adaptScale='</code> [ numeric | <em><code>1</code></em> ] - Speed of adaptation of the scale factor to deviations of acceptance ratios from the target ratio, <code>targetAR</code>.</p></li>
<li><p><code>'burnin='</code> [ numeric | <em><code>0.10</code></em> ] - Number of burn-in draws entered either as a percentage of total draws (between 0 and 1) or directly as a number (integer greater that one). Burn-in draws will be added to the requested number of draws <code>ndraw</code> and discarded after the posterior simulation.</p></li>
<li><p><code>'estTime='</code> [ <code>true</code> | <em><code>false</code></em> ] - Display and update the estimated time to go in the command window.</p></li>
<li><p><code>'firstPrefetch='</code> [ numeric | <em><code>Inf</code></em> ] - First draw where parallelised pre-fetching will be used; <code>Inf</code> means no pre-fetching.</p></li>
<li><p><code>'gamma='</code> [ numeric | <em><code>0.8</code></em> ] - The rate of decay at which the scale and/or the proposal covariance will be adapted with each new draw.</p></li>
<li><p><code>'initScale='</code> [ numeric | <code>1/3</code> ] - Initial scale factor by which the initial proposal covariance will be multiplied; the initial value will be adapted to achieve the target acceptance ratio.</p></li>
<li><p><code>'lastAdapt='</code> [ numeric | <em><code>Inf</code></em> ] - Last point at which the proposal covariance will be adapted; <code>Inf</code> means adaptation will continue until the last draw. Can also be entered as a percentage of total draws (a number strictly between 0 and 1).</p></li>
<li><p><code>'nStep='</code> [ numeric | *<code>1</code> ] - Number of pre-fetched steps computed in parallel; only works with <code>firstPrefetch=</code> smaller than <code>NDraw</code>.</p></li>
<li><p><code>'progress='</code> [ <code>true</code> | <em><code>false</code></em> ] - Display progress bar in the command window.</p></li>
<li><p><code>'saveAs='</code> [ char | <em>empty</em> ] - File name where results will be saved when the option <code>'saveEvery='</code> is used.</p></li>
<li><p><code>'saveEvery='</code> [ numeric | <em><code>Inf</code></em> ] - Every N draws will be saved to an HDF5 file, and removed from workspace immediately; no values will be returned in the output arguments <code>Theta</code>, <code>LogPost</code>, <code>AR</code>, <code>Scale</code>; the option <code>'saveAs='</code> must be used to specify the file name; <code>Inf</code> means a normal run with no saving.</p></li>
<li><p><code>'targetAR='</code> [ numeric | <em><code>0.234</code></em> ] - Target acceptance ratio.</p></li>
</ul>
<h4 id="description">Description</h4>
<p>The function <code>poster/arwm</code> returns the simulated chain of parameters and the corresponding value of the log posterior density. To obtain simulated sample statistics for each parameter (such as posterior mean, median, percentiles, etc.) use the function <a href="../poster/stats.html"><code>poster/stats</code></a> to process the simulated chain and calculate the statistics.</p>
<p>The properties of the posterior object returned as the 4th output argument are updated so that they capture the final state of the posterior simulations. This can be used to initialize a next simulation at the point where the previous ended.</p>
<h5 id="parallelised-arwm">Parallelised ARWM</h5>
<p>Set <code>'nStep='</code> greater than <code>1</code>, and <code>'firstPrefetch='</code> smaller than <code>NDraw</code> to start a pre-fetching parallelised algorithm (pre-fetched will be all draws starting from <code>'firstPrefetch='</code>); to that end, a pool of parallel workers (using e.g. <code>matlabpool</code> from the Parallel Computing Toolbox) must be opened before calling <code>arwm</code>.</p>
<p>With pre-fetching, all possible paths <code>'nStep='</code> steps ahead (i.e. all possible combinations of reject/accept) are pre-evaluated in parallel, and then the resulting path is selected. Adapation then occurs only every <code>'nStep='</code> steps, and hence the results will always somewhat differ from a serial run. Identical results can be obtained by turning down adaptation before pre-fetching starts, i.e. by setting <code>'lastAdapt='</code> smaller than <code>'firstPrefetch='</code> (and, obviously, by re-setting the random number generator).</p>
<h4 id="references">References</h4>
<ul>
<li><p>Brockwell, A.E., 2005. &quot;Parallel Markov Chain Monte Carlo Simulation by Pre-Fetching,&quot; CMU Statistics Dept. Tech. Report 802.</p></li>
<li><p>Strid, I., 2009. &quot;Efficient parallelisation of Metropolis-Hastings algorithms using a prefetching approach,&quot; SSE/EFI Working Paper Series in Economics and Finance No. 706.</p></li>
</ul>
<h4 id="example">Example</h4>

</body>
<div class="copyright">IRIS Toolbox. Copyright &copy; 2007-2014 Jaromir Benes.</div>
</html>
